@wervt/cms 0.0.5 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +177 -18
  2. package/dist/editor/assets/Button-DrsXdow7.js +6 -0
  3. package/dist/editor/assets/RichTextInput-BrNTSUXL.js +271 -0
  4. package/dist/editor/assets/Toast-DsP3Sdxg.js +13 -0
  5. package/dist/editor/assets/index-CWQLsBfF.js +16 -0
  6. package/dist/editor/assets/index-esGfkiTV.css +2 -0
  7. package/dist/editor/index.html +3 -3
  8. package/dist/editor-theme.d.ts +3 -0
  9. package/dist/editor-theme.js +18 -1
  10. package/dist/module.d.ts +18 -1
  11. package/dist/module.js +95 -7
  12. package/dist/routes.js +16 -0
  13. package/dist/runtime/app/edit-button.d.ts +7 -0
  14. package/dist/runtime/app/edit-button.js +56 -0
  15. package/dist/runtime/app/preview.client.js +12 -5
  16. package/dist/runtime/app/useCmsCollection.d.ts +24 -0
  17. package/dist/runtime/app/useCmsCollection.js +74 -0
  18. package/dist/runtime/app/useCmsSeo.d.ts +7 -0
  19. package/dist/runtime/app/useCmsSeo.js +31 -0
  20. package/dist/runtime/collections.d.ts +25 -0
  21. package/dist/runtime/collections.js +81 -0
  22. package/dist/runtime/editor-link.d.ts +19 -0
  23. package/dist/runtime/editor-link.js +31 -0
  24. package/dist/runtime/fields.d.ts +33 -1
  25. package/dist/runtime/fields.js +143 -7
  26. package/dist/runtime/pages.d.ts +11 -2
  27. package/dist/runtime/pages.js +37 -7
  28. package/dist/runtime/preview.d.ts +5 -2
  29. package/dist/runtime/preview.js +2 -2
  30. package/dist/runtime/schema.d.ts +187 -13
  31. package/dist/runtime/schema.js +115 -1
  32. package/dist/runtime/seo.d.ts +22 -0
  33. package/dist/runtime/seo.js +33 -0
  34. package/dist/runtime/server/access.get.d.ts +4 -0
  35. package/dist/runtime/server/access.get.js +8 -0
  36. package/dist/runtime/server/access.js +1 -1
  37. package/dist/runtime/server/collection.get.d.ts +12 -0
  38. package/dist/runtime/server/collection.get.js +28 -0
  39. package/dist/runtime/server/dev-images.d.ts +4 -1
  40. package/dist/runtime/server/dev-images.js +28 -2
  41. package/dist/runtime/server/entries.d.ts +53 -0
  42. package/dist/runtime/server/entries.js +83 -1
  43. package/dist/runtime/server/entry.delete.d.ts +4 -0
  44. package/dist/runtime/server/entry.delete.js +31 -0
  45. package/dist/runtime/server/entry.get.js +6 -6
  46. package/dist/runtime/server/entry.put.d.ts +1 -0
  47. package/dist/runtime/server/entry.put.js +20 -8
  48. package/dist/runtime/server/file-store.d.ts +14 -3
  49. package/dist/runtime/server/file-store.js +44 -9
  50. package/dist/runtime/server/image.delete.d.ts +4 -0
  51. package/dist/runtime/server/image.delete.js +24 -0
  52. package/dist/runtime/server/images.get.d.ts +5 -0
  53. package/dist/runtime/server/images.get.js +11 -0
  54. package/dist/runtime/server/library.d.ts +14 -0
  55. package/dist/runtime/server/library.js +72 -0
  56. package/dist/runtime/server/links.get.d.ts +7 -0
  57. package/dist/runtime/server/links.get.js +35 -0
  58. package/dist/runtime/server/media.d.ts +74 -0
  59. package/dist/runtime/server/media.js +88 -0
  60. package/dist/runtime/server/schema.get.d.ts +8 -0
  61. package/dist/runtime/server/schema.get.js +17 -7
  62. package/dist/runtime/server/store.d.ts +11 -2
  63. package/dist/runtime/server/store.js +110 -20
  64. package/dist/runtime/server/upload.post.js +3 -2
  65. package/dist/runtime/server/versions.get.d.ts +20 -0
  66. package/dist/runtime/server/versions.get.js +36 -0
  67. package/package.json +3 -2
  68. package/dist/editor/assets/Button-Dai6Ph2c.js +0 -6
  69. package/dist/editor/assets/RichTextInput-CdL9ZFoP.js +0 -271
  70. package/dist/editor/assets/Toast-BaUcosq6.js +0 -13
  71. package/dist/editor/assets/index-CP6dGIyl.css +0 -2
  72. package/dist/editor/assets/index-Du-lvx2V.js +0 -16
package/README.md CHANGED
@@ -52,24 +52,119 @@ const home = useCms('home')
52
52
  saves, so a page works before anyone edits it. Pages must render on the server (no prerendering),
53
53
  or edits only show after the next build.
54
54
 
55
+ ## Collections
56
+
57
+ Content that comes in any number (news, events, jobs) is a collection: one `cms/*.ts` describes an
58
+ item, and the owner adds and deletes items in the editor.
59
+
60
+ ```ts [cms/news.ts]
61
+ import { date, defineCmsCollection, richText, text } from '@wervt/cms/schema'
62
+
63
+ export default defineCmsCollection(
64
+ 'news',
65
+ { title: text('', { required: true }), date: date(), body: richText() },
66
+ { label: 'News', path: '/news/[slug]', sort: '-date' },
67
+ )
68
+ ```
69
+
70
+ ```ts
71
+ const news = await useCmsCollection('news') // ComputedRef of items, in the collection's order
72
+ const post = await useCmsItem('news', () => String(route.params.slug)) // ComputedRef, null when none
73
+ ```
74
+
75
+ Each item is its fields plus `slug` and, with a `path`, `path`. Both composables are awaitable like
76
+ `useFetch`; await them so a `[slug].vue` page can answer 404 on the server when `post.value` is
77
+ `null`. In the editor's preview they show what the form holds, an item not saved yet included.
78
+
79
+ - `slug`: lowercase letters, digits and single dashes, at most 100 characters. The editor suggests
80
+ it from the title (`Café am Sonntag` → `cafe-am-sonntag`, `-2` when taken). It can't be renamed.
81
+ - `path`: needs `[slug]`. Without it items are only listed.
82
+ - `sort`: a field name, `-` first for descending. Empty values come last either way; ties go by
83
+ slug. Defaults to the title.
84
+ - `titleField`: a `text()` field that names items in the editor; the first `text()` by default.
85
+
86
+ An item is stored as an entry under `<collection>/<slug>`, so everything said about entries below
87
+ holds for items: the file in `nuxt dev`, the database deployed, the newer one wins, 50 versions.
88
+ A deleted item is saved as `{ "$deleted": true }` rather than dropped, so a copy in the other
89
+ store (an older `cms/entries.json`, say) doesn't bring it back; its slug can be used again. A
90
+ collection key is one word without `/`; a page whose key is the collection's or under it is left
91
+ out with a warning.
92
+
55
93
  ## Fields
56
94
 
57
- | Field | The page gets | Notes |
58
- | -------------------------- | ----------------------- | ---------------------------------------------------------- |
59
- | `text('…')` | `string` | `{ multiline: true }` for several lines |
60
- | `richText('…')` | `string` (Markdown) | shown with `<CmsRichText :value>` |
61
- | `toggle(true)` | `boolean` | |
62
- | `link({ label, href })` | `{ label, href }` | `href`: a path, `#…`, `https://`, `mailto:` or `tel:` |
63
- | `image('/a.jpg')` | `{ src, srcset?, alt }` | always an image; `image()` without a default can be `null` |
64
- | `list({ …fields }, [ … ])` | an array of items | saved as a whole; each item gets the fields' defaults |
65
- | `{ …fields }` | an object | a group of fields shown together |
95
+ | Field | The page gets | Notes |
96
+ | ------------------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------- |
97
+ | `text('…')` | `string` | `{ multiline: true }` for several lines |
98
+ | `richText('…')` | `string` (Markdown) | shown with `<CmsRichText :value>` |
99
+ | `toggle(true)` | `boolean` | |
100
+ | `number(12.5)` | `number` | always a number; `number()` without a default can be `null` |
101
+ | `select(['a', 'b'], 'a')` | `'a' \| 'b'` | one of the options; `{ value, label }` names one in the editor |
102
+ | `date('2026-08-05')` | `string` | `YYYY-MM-DD`, or with `{ time: true }` `YYYY-MM-DDTHH:mm`; `date()` can be `null` |
103
+ | `link({ label, href })` | `{ label, href }` | `href`: a path, `#…`, `https://`, `mailto:` or `tel:` |
104
+ | `image('/a.jpg')` | `{ src, srcset?, alt, position? }` | always an image; `image()` without a default can be `null`; `{ focus: true }` see [Images](#images) |
105
+ | `list({ …fields }, [ … ])` | an array of items | saved as a whole; each item gets the fields' defaults |
106
+ | `{ …fields }` | an object | a group of fields shown together, titled by its name |
107
+ | `group({ …fields })` | an object | the same group, with `{ label }` for its title |
108
+ | `seo({ title, description, image })` | `{ title, description, image }` | the page's search and share texts, see [Search and sharing](#search-and-sharing) |
109
+
110
+ Every field and group takes `{ label }` for the editor and `{ hint }`, a line under it on what
111
+ goes in. Keep field names and page keys stable: a renamed field shows its default again (the old
112
+ value is kept, but no longer shown).
113
+
114
+ `text` and `richText` take `{ required: true }` (not empty) and `{ maxLength: 80 }` (characters
115
+ as people count them; Markdown formatting counts for `richText`), `link` takes `{ required: true }`
116
+ (an address is needed), `number` takes `{ min, max }` and `{ step }` for how far the editor's
117
+ buttons move it, and `date` takes `{ min, max }` written like its value. The editor marks such fields, counts characters and refuses to save until
118
+ they fit; the API answers `400` with the field's path for a value that doesn't. A field left out of
119
+ a `PUT` keeps its default and isn't checked. A rule added later applies to the next save, not to
120
+ what is already saved.
121
+
122
+ ```ts
123
+ title: text('Café Rosa', {
124
+ label: 'Name',
125
+ hint: 'Shown at the top of every page and in the browser tab.',
126
+ required: true,
127
+ maxLength: 40,
128
+ }),
129
+ ```
66
130
 
67
- Every field takes `{ label }` for the editor. Keep field names and page keys stable: a renamed
68
- field shows its default again (the old value is kept, but no longer shown).
131
+ A date has no time zone: `date('2026-08-05T18:30', { time: true })` means 18:30 wherever the page
132
+ is rendered. Turn it into a `Date` from its parts or with a time appended, never with
133
+ `new Date('2026-08-05')`, which is midnight in UTC and the day before west of it:
134
+
135
+ ```ts
136
+ const day = new Date(`${cms.value.opening}T00:00`)
137
+ day.toLocaleDateString('de-DE', { dateStyle: 'long' }) // 5. August 2026
138
+ ```
69
139
 
70
140
  Saved values that no longer fit a field (it changed from text to a list, say) are ignored and the
71
141
  default shows, so changing `cms/` never breaks a page.
72
142
 
143
+ ## Search and sharing
144
+
145
+ `seo()` adds the page's title, description and share image as fields the owner can edit, in a
146
+ section of its own in the editor. `useCmsSeo('home')` on the page turns them into `<title>`,
147
+ `description`, Open Graph and Twitter tags, the image as an absolute URL:
148
+
149
+ ```ts
150
+ // cms/home.ts
151
+ export default defineCmsPage('home', {
152
+ // …
153
+ seo: seo({ description: 'Coffee and cake in Freiburg.', image: '/og.jpg' }),
154
+ })
155
+ ```
156
+
157
+ ```vue
158
+ <script setup lang="ts">
159
+ const home = useCms('home')
160
+ useCmsSeo('home')
161
+ </script>
162
+ ```
163
+
164
+ A field left empty sets nothing, so the page's own `useHead` title (or the app's) stays until the
165
+ owner writes one. Call it on the page the content describes, not in a layout: `useCms` alone never
166
+ touches the head, so a footer can read the page's content on every route.
167
+
73
168
  ## Rich text
74
169
 
75
170
  A `richText` field holds Markdown: bold, italic, links, headings and lists, written in the editor
@@ -96,7 +191,30 @@ sending them.
96
191
  Commit it with `cms/entries.json`; the deploy ships both.
97
192
 
98
193
  The stored value is `{ id }` for an upload or `{ src }` for a file the app ships with, plus an
99
- optional `alt`. Saving what `GET` answered stores the same thing again.
194
+ optional `alt` and `focus`. Saving what `GET` answered stores the same thing again.
195
+
196
+ The editor's media library (_Media library_ in the page menu and the `⋮` menu) lists the uploads, newest
197
+ first, with the pages and items that use them, takes several uploads at once and deletes images
198
+ nothing uses. An image field's _From library_ button picks one of them. Uses come from a walk over
199
+ every saved entry's raw value, not the schema, so a field removed since still keeps its image; an
200
+ image held only in the open, unsaved form counts too, on the editor's side. Earlier versions don't
201
+ count: bringing one back whose image was deleted shows it broken. Deployed, images under
202
+ `public/cms/` that content uses but the bucket doesn't hold are listed as shipped with the app and
203
+ can't be deleted. Uploads keep their original file name in the bucket's metadata; `nuxt dev` keeps
204
+ none and shows the date instead.
205
+
206
+ With `image('/hero.jpg', { focus: true })` the owner taps what must stay in view where the page
207
+ crops the picture. The point is stored as `focus: { x, y }` in percent from the top left, and the
208
+ page gets it as `position` for `object-position`, unset when there is none:
209
+
210
+ ```vue
211
+ <img
212
+ :src="hero.src"
213
+ :alt="hero.alt"
214
+ class="h-64 w-full object-cover"
215
+ :style="{ objectPosition: hero.position }"
216
+ />
217
+ ```
100
218
 
101
219
  ## Where entries live
102
220
 
@@ -116,16 +234,31 @@ reads it with the saved fields over `defaults`.
116
234
  The editor is at `/_cms` on the site: one form per page in `cms/`, made for phones too. Lists
117
235
  can be reordered, images come from the camera or the gallery, and a page defined with
118
236
  `{ label, path }` (`defineCmsPage('home', { … }, { label: 'Home', path: '/' })`) shows its label
119
- and a button that opens it on the site. `/_cms?key=<key>` opens one page. It speaks English and German, after the browser's language.
237
+ and a button that opens it on the site. `/_cms?key=<key>` opens one page. It speaks English and German: the site's language
238
+ (`app.head.htmlAttrs.lang`) when it is one of them, otherwise the browser's. `cms: { editor: { locale: 'de' } }` sets it.
239
+
240
+ Once someone opened `/_cms` signed in as an editor, the site shows an _Edit_ button in a bottom
241
+ corner of its pages, in that browser only (`cms.editor.button`: `'left'`, the default, `'right'`
242
+ or `false`). It opens `/_cms?path=<the page's path>`: that page in the preview, its form when a
243
+ CMS page has that `path`. The editor writes its answer from `GET /api/_cms/access` to
244
+ `localStorage`, which the site's client plugin reads, so visitors send no request and every
245
+ visitor gets the same HTML. The button sits in a shadow root with its own styles. `path` only takes
246
+ paths of the site outside `/_cms`; anything else opens the editor as without it.
120
247
 
121
248
  A menu lists the pages. Pages with a `path` form a tree by their paths, so `/menu/drinks` sits
122
- under `/menu`; pages without one (a footer, say) are listed apart as content on every page. When
249
+ under `/menu`; pages without one (a footer, say) are listed apart as content on every page.
250
+ Collections follow as their own group. One opens as the list of its items (searchable past five);
251
+ _New_ asks for title and slug and opens a form that stays local until its first save, after which
252
+ the preview goes to the item's page. _Delete_ in the `⋮` menu deletes the open item and reloads
253
+ the preview. When
123
254
  the editor shows only the form on a wide screen, the menu is a sidebar; next to the preview and on
124
255
  phones it opens from the button left of the page's name.
125
256
 
126
257
  Next to the form, the editor shows the site with what's in the form, saved or not. On a wide
127
- screen the form is a sidebar beside the site; on a phone the site fills the screen and the form is
128
- a sheet over it, dragged up or down by its handle. A page with a `path` opens there; other pages
258
+ screen the form is a sidebar beside the site, on the left unless `cms.editor.sidebar` is `'right'`;
259
+ on a phone the site fills the screen and the form is a sheet over it, dragged up or down by its
260
+ handle. The eye button in the form's header hides the preview for the form alone, and the `⋮` menu
261
+ moves the sidebar to the other side. The editor keeps both choices in the browser. A page with a `path` opens there; other pages
129
262
  (a footer, say) show on whatever page the site is on, which is the first page with a `path` when
130
263
  the editor opens on them. Following a link on the site opens that page's form, unless the current
131
264
  one has unsaved changes. The site gets these values through a small client plugin that does
@@ -136,9 +269,35 @@ The API behind it:
136
269
 
137
270
  - `GET /api/_cms/entries/<key>`: the page's values, defaults filled in. Public.
138
271
  - `PUT /api/_cms/entries/<key>`: saves; the body is the value. Checked against the page's
139
- fields, with a `400` that names the field that doesn't fit.
140
- - `GET /api/_cms/schema`: the pages and their fields. Public.
272
+ fields, with a `400` that names the field that doesn't fit. With `If-Match: "<updatedAt>"`
273
+ (the `updatedAt` from `GET`) or `If-None-Match: *` (a page never saved) it saves only over that
274
+ version; anything newer answers `412` with the current `updatedAt` in `data`. The editor sends
275
+ it and, on a `412`, offers to load the other version or save over it. Without either header the
276
+ save always wins, so scripts and agents work as before.
277
+ - `DELETE /api/_cms/entries/<collection>/<slug>`: deletes an item, with `If-Match` as for `PUT`;
278
+ `404` when there is none. Editors only.
279
+ - `GET /api/_cms/collections/<key>`: the items in the collection's order, as
280
+ `{ items: [{ key, slug, path?, value, updatedAt }] }`. Public.
281
+ - `GET /api/_cms/schema`: the pages and collections with their fields. Public.
141
282
  - `POST /api/_cms/images`: uploads an image (see above).
283
+ - `GET /api/_cms/images`: the media library, as `{ images: [{ name?, value, image, thumb,
284
+ fileName?, size?, uploadedAt?, uses: [{ key, title, alt? }] }] }`. `name` is missing for shipped
285
+ images. Editors only.
286
+ - `DELETE /api/_cms/images/<name>`: deletes an upload; `409` with `data.uses` while saved content
287
+ uses it, `404` when there is none. Editors only.
288
+ - `GET /api/_cms/access`: `{ editor: true }` when the signed-in person may edit, `401` or `403`
289
+ otherwise.
290
+ - `GET /api/_cms/links`: the site's pages a link can point to (routes without parameters and
291
+ CMS pages with a `path`), as `{ path, label? }`. Editors only.
292
+ - `GET /api/_cms/versions/<key>`: the entry's saved versions, newest (the current one) first:
293
+ `updatedAt`, `by` (the editor's address) and `changed` (the top-level fields that differ from
294
+ the version before). `?at=<updatedAt>` answers that version with its values filled in like
295
+ `GET /entries`. Editors only: an earlier version may hold what someone took down on purpose.
296
+
297
+ The `⋮` menu's **Earlier versions** lists them. Picking one puts it into the form and the
298
+ preview as an unsaved change; saving brings it back, through the same conflict check as any save.
299
+ The last 50 versions per entry are kept: deployed in the `cms_entry_versions` table, under
300
+ `nuxt dev` in `.data/cms-history.json` (not committed).
142
301
 
143
302
  The app's owner, members and wervt admins can edit, once signed in at `/_wervt/login` (the
144
303
  editor links there; in `nuxt dev` it signs you in as the owner). To let others edit, list their